PATH Mac OS X Server Documentation > Mac OS X Server Release Notes

Mac OS X Server Developer Release Notes:
Java Debugger Command Reference

Overview

This file summarizes the commands for the Java debugger, which is available through Project Builder. The complete set of commands is given below. Any unique command prefix is recognized (e.g. "du" for "dump"). If a prefix is not unique, the debugger will tell you. Several commands have short aliases (for example, "si" for "stepi" and "bt" for "backtrace"). The case of a command does not matter (for instance, "Break" = "break" = "BrEaK"). The case of arguments may matter (for example, class and file names must match case: "Exception" is not the same as "exception").

JavaBug>> mumble
 ERROR: No command prefix matches "mumble"b <fileName>:<lineNum> | <class>:<method> -- set a breakpoint
backtrace -- backtrace: show stack info
break <fileName>:<lineNum> | <class>:<method> -- set a breakpoint
bt -- backtrace: show stack info
catch className -- catch exceptions for exception class className
clear Num -- clear (delete) breakpoint number Num
continue -- continue execution from a breakpoint
dir [path] -- get or set dir(ectory) search path
disable Num -- disable breakpoint number Num
down [Num] -- set default frame down Num|1 frames
drop className -- drop (stop catching) exceptions for class className
dump object -- print object's struct(ure)
enable Num -- enable breakpoint number Num
finish -- step Out (finish executing current stack frame)
frame [Num] -- show stack frame info for stack[Num] or current frame
getprop name -- get system property
group [groupName] -- if groupName then set curent thread group,
else show information for thread groups and their threads
list -- list source lines around current frame (if available)
next -- step Over<p* object -- print object's struct(ure)
po object -- invoke object's toString() method
print object -- invoke object's toString() method
resume -- resume all threads
si -- execute a single bytecode instruction (step into)
step -- step Into
stepi -- execute a single bytecode instruction (step into)
suspend -- suspend all threads
thread threadNum -- set current thread to threadNum
up [Num] -- set default frame up Num|1 frames

Thread Commands

In the Java debugger, there is a current thread group and a current thread. When an exception occurs, the current thread is reset. The current thread group is always the thread group containing the current thread.

Group [groupName] This command lists thread groups and threads. If a groupName is given, the current thread group is set to that name. To avoid confusion ,thread groups are referred to by name, while threads within a group are referred to by number.

Thread threadNum This command sets the thread within the current thread group. To find out the current group and thread, type group.

Examples:

JavaBug>> group




Group: system
1 Finalizer thread cond. waiting
2 JavaBug cond. waiting
3 Debugger agent running
4 Breakpoint handler cond. waiting
5 Step handler cond. waiting
6 Agent input cond. waiting
7 main suspended< Group: main
1 main suspended
 CURRENT GROUP is "system"CURRENT THREAD within the group is "main" JavaBug>> thread 6
 Current thread now Agent input, state=cond. waiting

Backtrace This command displays the contents of the current thread's Java stack. (Currently, only Java stack frames are printed. No "native" (non-Java) frames appear). An alias for backtrace is bt.

JavaBug>> bt
 [0] java.io.PipedInputStream.read (PipedInputStream:201) pc = 80
[1] java.io.PipedInputStream.read (PipedInputStream:242) pc = 43
[2] java.io.BufferedInputStream.fill (BufferedInputStream:135) pc = 164
[3] java.io.BufferedInputStream.read (BufferedInputStream:162) pc = 12
[4] java.io.FilterInputStream.read (FilterInputStream:81) pc = 4
[5] sun.tools.debug.AgentIn.run (AgentIn:46) pc = 20
[6] java.lang.Thread.run (Thread:474) pc = 11

Stack inspection commands (frame, up, down, print, dump) require that the thread being inspected is suspended. Threads are suspended by hitting a breakpoint, or by the suspend command.

Frame [frameNum] This command displays the arguments and local variables for the current frame or the frame number frameNum . Frame numbers are absolute and are the numbers displayed in the backtrace. Note that Java code must have been compiled with javac's -g flag or local and argument information is not available to the debugger. The frame command resets the current frame.

JavaBug>> backtrace
 [0] com.apple.alpha.core.MutableDictionary.<init> (MutableDictionary:213) pc = 0
[1] Document.setRichText (Document:534) pc = 10<[2] Document.toggleRich (Document:596) pc = 69
 JavaBug>> frame 1
 [1] setRichText(flag=true)
<local> view = <NSTextView: 0x194b8c0>Frame = {{0.00, 0.00}, {490.00, 420.00}}, Bounds = {{0.00, 0.00}, {490.00, 420.00}}
Horizontally resizable: NO, Vertically resizable: YES
MinSize = {490.00, 420.00}, MaxSize = {340282346638528859811704183484516925440.00, 340282346638528859811704183484516925440.00}

Up [numFrames] This command resets the current frame up (toward older frames => higher frame numbers) relative to the current frame. If numFrames is not given, 1 is used.

Down [numFrames] This command resets the current frame down (toward newer frames => lower frame numbers) relative to the current frame. If numFrames is not given, 1 is used.

Print object This command prints the object object by calling its toString() method. An alias for print is po (for Print Object).

JavaBug>> po view
 view = <NSTextView: 0x194b8c0>Frame = {{0.00, 0.00}, {490.00, 420.00}}, Bounds = {{0.00, 0.00}, {490.00, 420.00}}
Horizontally resizable: NO, Vertically resizable: YES
MinSize = {490.00, 420.00}, MaxSize = {340282346638528859811704183484516925440.00, 340282346638528859811704183484516925440.00}

Dump object This command prints the object object structurally. An alias for dump is p* (from gdb usage for Print *=reference).

JavaBug>> p* view
view = (com.apple.alpha.app.TextView)0x3bc0c0 {
private int instance = 26523840
}
 JavaBug>> p* 0x3bc0c0
 0x3bc0c0 = (com.apple.alpha.app.TextView)0x3bc0c0 {
private int instance = 26523840
}

(In the above case, the object is obviously a native object with a peer class.)

List This command displays source text for the current frame--when it can find it. (Note the dir command, below).

JavaBug>> break Document:setRichText
 Set breakpoint 2000 in method: setRichText at line 533 in file "Document.java" JavaBug>> cont
 JavaBug>> // breakpoint hit because of user action
Broken at 533 in "Document.java" JavaBug>> list
 File: "Document.java"529 return layoutManager().hyphenationFactor();
530 }
531
532 public void setRichText(boolean flag) {
533 => TextView view = firstTextView();
534 MutableDictionary textAttributes = new MutableDictionary(2);
535
536 isRichText = flag;
537

Control Functions

Suspend This command suspends all Java threads (which are not involved in debugging).

Resume This command resumes all Java threads (which are not involved in debugging).

Break [fileName:lineNumber] This command sets a breakpoint in file fileName at line lineNumber . An alias for break is b. With no arguments, it prints the current breakpoints.

Break [ClassName:methodName] This command sets a breakpoint at the start of method methodName in class ClassName . An alias for break is b. With no arguments, it prints the current breakpoints.

JavaBug>> break Document:setRichText
 Set breakpoint 2000 in method: setRichText at line 533 in file "Document.java" JavaBug>> break
 break <fileName>:<lineNum> | <class>:<method> -- set a breakpoint
2000 Document.java:533
 JavaBug>> disable 2000
 JavaBug>> break
break <fileName>:<lineNum> | <class>:<method> -- set a breakpoint
 2000 Document.java:533 [disabled]

Clear [breakNum] This command clears (forgets) the breakpoint numbered breakNum . With no argument, it prints the current breakpoints.

Disable [breakNum] This command disables, but does not clear, the breakpoint numbered breakNum .

Enable [breakNum] This command (re)enables the breakpoint numbered breakNum .

Continue When a thread is broken, this command continues (resumes) execution of that thread.

Step This command steps forward a line of code. If the code is a call, it steps into the call. If the call is to "native" (non-java) code, it steps over the code (acts like next ). If the step returns to native code, it acts like continue .

Setpi This command steps forward by a single bytecode instruction. It otherwise acts like step . (Currently, there is no command to display the bytecodes. Use "javap -c classFile " to see the bytecodes).

Next This command steps forward a line of code. If the code is a call, it steps over the call. If the step returns to native code, it acts like continue .

Finish This command steps to the end of the code in the current stack frame. (also know as "step out").

Catch ExceptionClass This command causes exceptions for class ExceptionClass and all its subclasses to act like a breakpoint. (At this time one cannot step through exception code one can only inspect the stack and continue ).

Drop ExceptionClass This command is the inverse of catch. The system will no longer break when an exception of class ExceptionClass is thrown.

Convience Functions

Dir [newClassPath] This command prints or sets the CLASSPATH used to search for debug and source information (e.g. for the list and frame commands).

GetProp [propName] This command prints the value for the specified property or all properties of the Java VM. JVM properties cannot be changed.